home *** CD-ROM | disk | FTP | other *** search
/ The Arsenal Files 6 / The Arsenal Files 6 (Arsenal Computer).ISO / prg_casm / jlvesa11.zip / JLVESA.DOC < prev    next >
Text File  |  1996-01-03  |  19KB  |  441 lines
  1. JLVesa VESA SVGA library v1.1
  2. Copyright 1994, 1995, 1996 Johannes Lehtinen
  3. All rights reserved
  4.  
  5.  
  6. COPYRIGHTS
  7. ----------
  8.  
  9.    This source code and library can be copied to third person on
  10.    condition that:
  11.  
  12.       -  All the files included in the original distribution packet
  13.          (JLVESA11.*) are copied at the same time
  14.       -  All the files are identical to the files included in the
  15.          original distribution packet (JLVESA11.*)
  16.       -  No carge is taken for copy nor for copying expenses
  17.  
  18.    This source code and library can be modified, compiled and linked
  19.    to your own source code on condition that:
  20.  
  21.       -  The compiled program will be freely distributable, _not_
  22.          commercial (shareware programs are considered commercial)
  23.       -  Your executable program clearly states to the user that you
  24.          have used "JLVesa library v1.1 by ABACUS" in your program
  25.       -  You are a registered JLVesa library user (registeration is
  26.          free)
  27.  
  28.  
  29. GENERAL DESCRIPTION
  30. -------------------
  31.  
  32.    JLVesa VESA SVGA library was made to handle all 256 color modes on
  33.    VESA compatible SVGA boards (in MS-DOS real-mode). It does not
  34.    include very large set of graphics functions, but it includes those
  35.    very basic functions needed for graphics output. The library was
  36.    made on 80386DX25, so it should be quite fast on up-to-date
  37.    equipment. I coded this library mainly for my own use and decided
  38.    only later to make it distributable. JLVesa VESA SVGA library is
  39.    offered as is. If you want to use it efficiently, you most
  40.    probably have to build-in your own modifications and extensions.
  41.  
  42.  
  43. AUTHOR OF THIS LIBRARY
  44. ----------------------
  45.  
  46.    Author of this library is Johannes Lehtinen (also known as Snowman
  47.    of Abacus, not _the_ Snowman :). You can contact me by following
  48.    methods:
  49.  
  50.       E-Mail:           johannes.lehtinen@hut.fi
  51.       Phone (voice):    +358-50-5163025
  52.       Snail-mail:       Johannes Lehtinen
  53.                         Muurlantie 340 B
  54.                         FIN-25130 MUURLA
  55.                         Finland
  56.  
  57.    Please use e-mail if possible! Please use Finnish or English!
  58.    Registerations, comments, bug reports and questions are always
  59.    welcome.
  60.  
  61.  
  62. REGISTERATION NOTES
  63. -------------------
  64.  
  65.    If you are going to use this library, you have to register yourself
  66.    to be registered JLVesa library user. The registeration is free and
  67.    the idea behind it is just to tell me how and by whom my library is
  68.    used. I can also use the registeration information to inform you
  69.    about new versions of this library, bugfixes or other related
  70.    ABACUS products.
  71.  
  72.    To register yourself, just send the following information to the
  73.    author:
  74.  
  75.       -  Your real name
  76.       -  Your alias and group (optional)
  77.       -  Contact information (e-mail address preferred)
  78.       -  Your location (City, State, Country)
  79.       -  Do you code for: Business, Pleasure, Both
  80.       -  Do you mainly code: Tools, Applications, Games, Demos/Intros
  81.  
  82.    If you would like to receive information about new ABACUS products,
  83.    please make sure that I have up-to-date contact information!
  84.  
  85.  
  86. WHAT NEW SINCE V1.0
  87. -------------------
  88.  
  89.    Not much, I have to admit :) The biggest difference is that the
  90.    documentation is now in English, not in Finnish. I have also fixed
  91.    couple of minor bugs. Only new routines are font handling routines.
  92.    I have also renamed functions, but if you are compiling old source
  93.    code or prefer old names, just define JV_OLD_FUNC_NAMES before
  94.    including jlvesa.h.
  95.  
  96.    Also source code of this library is now available (and should be
  97.    included in this packet). The source is far from clean or optimal,
  98.    but this library was my first library coded in pure assembler and
  99.    you can always code your own library if you want to.
  100.  
  101.  
  102. SOURCE CODE AND DEFINITIONS
  103. ---------------------------
  104.  
  105.    Source code was written for TASM (Ideal mode) and BC++ 3.1. The
  106.    makefile included is for Borland make. The source is not clean nor
  107.    well documented, but hey... I was coding this just for myself and
  108.    learning assembler at the same time :)
  109.  
  110.    I have used special C-types for following primitives:
  111.  
  112.       unsigned byte     <->   JVUByte     <->   unsigned char
  113.       signed byte       <->   JVSByte     <->   signed char
  114.       unsigned word     <->   JVUWord     <->   unsigned short int
  115.       signed word       <->   JVSWord     <->   signed short int
  116.       unsigned dword    <->   JVUDword    <->   unsigned long int
  117.       signed dword      <->   JVSDword    <->   signed long int
  118.  
  119.  
  120. HOW TO LINK WITH JLVESA
  121. -----------------------
  122.  
  123.    If you are using any standard MS-DOS C(++) -compiler, linking of
  124.    the library should be a routine procedure. Just include header file
  125.    jlvesa.h in the beginning of your code and link your executable
  126.    with jlvesa.lib. Some of the font routines were made in C++, so you
  127.    can't use them if you are compiling C. If you are using old
  128.    function names, remember to define JV_OLD_FUNC_NAMES before
  129.    including jlvesa.h. JLVesa library was compiled in large memory
  130.    model.
  131.  
  132.    Please report me if you get "strange" error messages on linking
  133.    stage.
  134.  
  135.  
  136. RUNNING PROGRAMS USING JLVESA
  137. -----------------------------
  138.  
  139.    Many graphics adapters, which are claimed to be hardware VESA
  140.    compatible have serious bugs in their VESA support. Some special
  141.    functions like changing the logical width of the screen might not
  142.    work on some cards. If you encounter this kind of problems, try to
  143.    run freely distributable UNIVBE driver before running the program.
  144.    UNIVBE is made to fix bugs in VESA emulations and it also works
  145.    like normal TSR VESA-driver for several common video cards. At
  146.    least some S3 and Cirrus cards have problems with their hardware
  147.    VESA support. UNIVBE fixes these problems.
  148.  
  149.    JLVesa was coded using 386-assembler, which means that you can't
  150.    run JLVesa programs on 8086/88/186/286!
  151.  
  152.  
  153. JLVESA FUNCTIONS
  154. ----------------
  155.  
  156.    Here you can find short descriptions for each of JLVesa functions.
  157.    First there are functions coded in pure 386 assembler. These are
  158.    C-type functions.
  159.  
  160.    JVFlag JVSVGA_GetInfo(JVSVGAInfo *info);
  161.  
  162.       This function is used to detect VESA and to obtain SVGA card
  163.       specific information (see the structure definition in jlvesa.h
  164.       for detailed information). Function returns 0 on success and 1
  165.       on failure (probably VESA not detected).
  166.  
  167.    JVFlag JVSVGA_GetModeInfo(JVUWord *mode, JVModeInfo *info);
  168.  
  169.       This function is used to obtain mode specific information (see
  170.       the structure definition in jlvesa.h for detailed information).
  171.       Function returns 0 on success and 1 on failure (probably mode
  172.       not available).
  173.  
  174.    JVUDWord JVSVGA_GetMemory(void);
  175.  
  176.       This function is used to obtain amount of memory on SVGA board
  177.       after SVGA mode has been set with JVSVGA_SetMode(). The size of
  178.       memory is returned in bytes. You can also use memory information
  179.       returned in function JVSVGA_GetInfo() if you want to get size of
  180.       video memory before actually entering SVGA mode.
  181.  
  182.    JVFlag JVSVGA_SetMode(JVUWord mode);
  183.  
  184.       This function is used to set a 256 color VESA mode. The function
  185.       also initializes some internal data structures, so you should
  186.       always set the mode with this function! Function returns 0 on
  187.       success and 1 on failure. Note that some VESA boards may have
  188.       exotic memorymapping techniques, which are not supported by
  189.       JLVesa! You can find the right mode number by using
  190.       JVSVGA_GetInfo() and JVSVGA_GetModeInfo() functions but there
  191.       are also couple of mode numbers, which always refer to the same
  192.       resolutions:
  193.  
  194.          Mode           Resolution
  195.  
  196.          0100H (256)    640x400/256
  197.          0101H (257)    640x480/256 (Very wide support, recommended)
  198.          0103H (259)    800x600/256
  199.          0105H (261)    1024x768/256
  200.          0107H (263)    1280x1024/256
  201.  
  202.    void JVSVGA_WaitForVRetrace(void);
  203.  
  204.       This function waits for vertical retrace to start. Use to make
  205.       smooth palette changes and page switches.
  206.  
  207.    void JVScreen_SetActive(JVUDword offset);
  208.  
  209.       This function sets the video memory offset of first pixel on
  210.       active video page (page that functions are drawing to). If you
  211.       are using double-buffered output (one page is on the screen
  212.       while another is drawn hidden), you could use for example
  213.       offsets 0 and (logical width * height) for active screen memory
  214.       offsets.
  215.  
  216.    JVFlag JVScreen_SetVisual(JVUWord pixel, JVUWord line);
  217.  
  218.       This function sets the video memory offset of first pixel on
  219.       visual video page (page that is visible on the screen). The
  220.       function works just like the previous one, but for some
  221.       strange (?) reason the offset is given indirectly. You have to
  222.       specify first visible line of video memory and first visible
  223.       pixel of that line. Some VGA boards can use only pixel values
  224.       divisible by 2/4/8/16. If you are trying to scroll the screen
  225.       pixel by pixel you can have rather strange effects on that kind
  226.       of cards.
  227.  
  228.       To convert simple video memory offset to line and pixel use
  229.       following form:
  230.  
  231.          line = offset / logical width
  232.          pixel = offset % logical width (% = modulo)
  233.  
  234.    JVUWord JVScreen_SetLogicalWidth(JVUWord lwidth);
  235.  
  236.       This function sets logical video memory width. Logical width
  237.       means that video memory has certain width, which can be wider
  238.       than actual screen width. If this is the case, then screen is
  239.       like a window to video memory and you can move that window up
  240.       and down, left and right on video memory. This means that you
  241.       can have for example 1028x1028 background picture on 640x480
  242.       resolution. By using the JVScreen_SetVisual() you can then
  243.       move the screen around video memory and the picture seems to be
  244.       scrolling around on the screen.
  245.  
  246.       It is not always possible to set the logical width to some
  247.       specific value. This depends on the video card used, but quite
  248.       often the logical width has to be divisible by 2/4/8/16/32 or
  249.       something like that. In this kind of situation, the logical
  250.       width is set to nearest possible value. This function returns
  251.       the new logical width.
  252.  
  253.    void JVScreen_ClearAll(JVUByte color);
  254.  
  255.       This functions overwrites the whole video memory with given
  256.       color value. However, the function uses JVSVGA_GetMemory() to
  257.       read the amount of video memory and that is why this function is
  258.       unreliable. It usually overwrites at least one screenfull of
  259.       video memory. If you want to be sure, use JVRectangle_Draw()
  260.       instead.
  261.  
  262.    void JVPixel_Draw(JVSWord x, JVSWord y, JVUByte color);
  263.  
  264.       This function draws pixel to the active page using given color.
  265.       Function checks that pixel is on screen before drawing it.
  266.  
  267.    JVUByte JVPixel_Read(JVSWord x, JVSWord y);
  268.  
  269.       This function reads the value of a pixel at given coordinates
  270.       (on active page). Operation is undefined outside the screen
  271.       area.
  272.  
  273.    void JVRectangle_Draw(JVSWord x, JVSWord y, JVUWord width, JVUWord height,
  274.                          JVUByte color);
  275.  
  276.       This function draws a rectangle to the active page. X and y are
  277.       the coordinates of upper left corner and width and heigth are
  278.       the dimensions of the rectangle. Rectangle is drawn using given
  279.       color. Only the part of rectangle that is inside a screen area
  280.       will be drawn.
  281.  
  282.    void JVLine_Draw(JVSWord x1, JVSWord y1, JVSWord x2, JVSWord y2,
  283.                     JVUByte color);
  284.  
  285.       This function draws a line to the active page. x1 and y1 are the
  286.       start coordinates and x2 and y2 are the end coordinates. Line is
  287.       drawn using given color. The line is not limited inside a screen
  288.       area! Please use JVLine_DrawLimited() to draw lines that are
  289.       partially outside the screen. This line drawing routine is not
  290.       optimized and I don't recommend using this routine for any speed
  291.       critical task.
  292.  
  293.    void JVImage_Draw(JVSWord x, JVSWord y, JVUWord width, JVUWord height,
  294.                      void *image);
  295.  
  296.       This function copies image from memory to the active page. The
  297.       image is stored in memory pixel by pixel from upper left corner
  298.       to lower right corner. X and y are the coordinates of upper left
  299.       corner and width and height are the dimensions of image.
  300.       Function limits image inside a screen area.
  301.  
  302.    void JVImage_DrawOn(JVSWord x, JVSWord y, JVUWord width,
  303.                        JVUWord height, void *image);
  304.  
  305.       This works almost exactly like the previous function. There is
  306.       one significant difference. This functions does not copy those
  307.       pixels to the memory which have value 0. This means that you can
  308.       have transparent images (transparent parts are defined using
  309.       color 0). The function is also much slower than the previous
  310.       one, so I recommend using JVImage_Draw() if possible.
  311.  
  312.    void JVImage_DrawLimited(JVSWord x, JVSWord y, JVUWord width,
  313.                             JVUWord height, void *image, JVSWord lx,
  314.                             JVSWord ly, JVUWord lwidth, JVUWord lheight);
  315.  
  316.       This function is a variation of JVImage_Draw(). The difference
  317.       is that the drawing area can be limited by user. Ly and lx are
  318.       the coordinates of upper left corner of the are and lwidth and
  319.       lheight are the dimensions of the area. Everything outside this
  320.       limited area will be left untouched.
  321.  
  322.    void JVImage_DrawOnLimited(JVSWord x, JVSWord y, JVUWord width,
  323.                               JVUWord height, void *image, JVSWord lx,
  324.                               JVSWord ly, JVUWord lwidth, JVUWord lheight);
  325.  
  326.       This function is exactly like the previous one but it is a
  327.       variation of JVImage_DrawOn().
  328.  
  329.    void JVImage_Read(JVSWord x, JVSWord y, JVUWord width, JVUWord height,
  330.                      void *image);
  331.  
  332.       This function copies image from the active page to memory. X and
  333.       y are the coordinates of image and width and height are the
  334.       dimensions of the image. Anything outside the screen area will
  335.       be undefined!
  336.  
  337.    void JVPalette_Set(JVPalette palette);
  338.  
  339.       This function sets the whole 256 color palette. Palette has
  340.       actual format of: unsigned char palette[256][3], but I am using
  341.       this own JVPalette type of mine. It is constructed of values of
  342.       type JVColor (unsigned char [3]).
  343.  
  344.    void JVColor_Set(JVUByte color, JVUByte red, JVUByte green, JVUByte blue);
  345.  
  346.       This functions sets RGB values for given color.
  347.  
  348.    JVUByte JVColor_Find(JVPalette palette, JVUByte red, JVUByte green,
  349.                         JVUByte blue);
  350.  
  351.       This function can be used if you want to search the given
  352.       palette for closest color to given RGB values. Colors are chosen
  353.       by their distance in a RGB color cube. Function returns the
  354.       nearest color found.
  355.  
  356.    void JVBIOS_SetMode(JVUByte mode);
  357.  
  358.       This function calls normal video BIOS function to set any video
  359.       mode. This function is used to exit from SVGA mode to normal
  360.       text mode (mode 3 is 80x25 color).
  361.  
  362.  
  363.    The following functions are C++-type functions coded in C. You can
  364.    not link them to C code (you have to use C++).
  365.  
  366.    void JVFont_Select(JVFont *font);
  367.  
  368.       This function is used to select a font. There are no plug and
  369.       play fonts available. You have to make your own fonts. The font
  370.       is basicly a serie of images with have specified dimensions. The
  371.       pointer given to this function has to point to font structure,
  372.       which has following format:
  373.  
  374.       typedef struct JVFont
  375.       {
  376.          JVUWord offset[256];       /* Offsets of character images. If the
  377.                                     *  character does not have corresponding
  378.                                     *  object, 0xFFFF is used. */
  379.          JVUWord height;            /* Height of font */
  380.          JVUWord width;             /* Default width for character cell.
  381.                                     *  Different characters may still have
  382.                                     *  different width. */
  383.          JVUByte *font_data;        /* Font images. First byte of image is
  384.                                      * the actual length of the character.
  385.                                      * Rest of the data is like any image. */
  386.       };
  387.  
  388.       You have to call this function before using any other font
  389.       functions.
  390.  
  391.    void JVText_Draw(int x, int y, char *string);
  392.  
  393.       This function puts text to the screen. X and y are the starting
  394.       position of the text.
  395.  
  396.    void JVFont_Colorize(JVUByte color);
  397.  
  398.       This function can be used to colorize a font. All pixels which
  399.       are visible (!=0) are overwritten with given color.
  400.  
  401.    int JVText_GetLength(char *string);
  402.  
  403.       This function returns the length of a string as a number of
  404.       pixels.
  405.  
  406.    void JVText_Input(int x, int y, char *string, int maxlength,
  407.                      JVUByte fgcolor, JVUByte bgcolor);
  408.  
  409.       This function is used to read input from user. The text is
  410.       written to given x and y coordinates using given foreground and
  411.       background colors. The maxlength is used to limit the number of
  412.       characters to read.
  413.  
  414.    void JVLine_DrawLimited(int x1, int y1, int x2, int y2, JVUByte color,
  415.                            int xl, int yl, int width, int height);
  416.  
  417.       This function is addition to JVLine_Draw(). It just limits the
  418.       line inside the given area. Xl and yl are the coordinates of
  419.       upper left corner of the area and width and height are the
  420.       dimensions of the area.
  421.  
  422.  
  423. EXAMPLE
  424. -------
  425.  
  426. Please, take a look at the example JVEXMPLE.EXE and the source code of
  427. it (JVEXMPLE.CPP). It demonstrates the most primitive use of these
  428. functions. The example runs in 640x480/256 mode to support also
  429. computers with an SVGA video adapter but a standard VGA monitor.
  430.  
  431.  
  432. Okay... I hope that this will help someone to do VESA compatible
  433. graphics stuff. If you have any suggestions or bug reports, I would
  434. like to hear them. I am also interested in all kind of extensions
  435. made.
  436.  
  437.  
  438. The author,
  439. Johannes Lehtinen
  440.  
  441.